Preface: This is a text-only version of the Listen Operator's Manual. Sections pertaining to the Liscensing Agreement and Warranty apply only to registered versions of the product. Unregistered, Shareware versions of Listen may be freely distributed and are distinquished from the registered version only by the addition of Registration Reminder Screens and a time limit placed on an active monitoring session. Listen... A Serial Data Line Monitor for Windows 1. Introduction..A Word about Shareware 1.1 What Shareware is 1.2 Advantages of Registration. 1.3 Registration of the Listen Application 1.4 Licensing Agreement 1.5 Warranty 2. Listen System Requirements 2.1 Operational Overview 2.2 System/Cabling Requirements 2.3 .INI File Parameters 3. Installation 3.1 Making Backups 3.2 Installing Listen 4. Basic Menu Selections 4.1 ToolBar 4.2 Hardware Setup 4.3 Display Preferences 4.3.1 Color & Font Selection 4.3.2 Non-Printing Character Display 4.4 ASCII Table 4.5 StatusBar 5. Monitoring Data Communications 5.1 Menu Options 5.2 Scrolling Characteristics 6. Browsing Captured Data 6.1 Browse Menu Options 6.2 Block Operations 6.2.1 Print 6.2.2 Copy to Clipboard 6.2.3 Search/Find 6.2.4 Checksum Calculator 7. Using Filters 7.1 Byte Filters 7.2 Block Filters 8. Trap Buffer Operation 8.1 Trap Buffer Operation 8.2 Trigger 8.3 Browsing the Trap Buffer 9. Technical Support 9.1 Contacting WinTECH 1. Introduction..A Word about Shareware 1.1 What is Shareware Shareware is a distribution method, not a type of software. Shareware products may be freely distributed among potential users with each user given an opportunity to fully evaluate the software over a specified period of time. This distribution method gives users a chance to try software before buying it. If the particular shareware application provides a service that the user wishes to continue beyond the specified evaluation period, a registration payment to the software author is required. Copyright laws apply to both Shareware and commercial software, and WinTECH Software retains all rights to its software products with the following exception: WinTECH Software specifically grants the right to copy and distribute unregistered copies of the Listen Application to all interested parties for an evaluation period not to exceed thirty-days. 1.2 Advantages of Registration The Shareware distribution system depends upon the integrity of the user to make the required registration payment only if the application proves itself useful. Shareware products have the ultimate money-back guarantee. If the product is not used, no payment is required. Registration of Shareware products support this system of distribution and allow continued development of low-cost high quality software solutions. 1.3 Registration of the Listen Application Unregistered copies of the Listen Application are functionally equivalent to registered copies with the following exception: To encourage registration, a limit is placed on the amount of time data may be collected during a monitoring session. This limit does not effect the ability of a user to fully evaluate either the functionality or through-put of the application. Registration of the Listen Application requires a registration fee of $49.95 be submitted to WinTECH Software. The user shall receive in return the most recent registered version of Listen with all time limit constraints and registration reminder screens disabled. The user shall also receive a printed user manual, and free technical support for a period of three months after registration. Registered users also have direct access to the Listen design engineer and a commitment from WinTECH to consider product enhancements based on individual application requirements. In other words, if you can think of anything that would make your life easier, let us know. If it has general marketing appeal, chances are it could be included in the next revision. 1.4 Licensing Agreement Registered WinTECH software is protected by both United States Copyright Law and International Treaty provisions. Therefore, you must treat this software just like a book with the following single exception. WinTECH Software authorizes you to make archival copies of the software for the sole purpose of backing-up your software and protecting your investment from loss. By saying "just like a book," WinTECH means for example that this software may be used by any number of people and may be freely moved from one computer location to another so long as there is no possibility of it being used at two locations at the same time. Execution of two copies of the same registered Listen application at the same time constitutes a Copyright violation and is expressly prohibited. 1.5 Warranty With respect to the physical diskette and physical documentation enclosed herein, WinTECH Software warrants the same to be free of defects in materials and workmanship for a period of 30 days from the date of registration. In the event of notification within the warranty period of defects in material or workmanship, WinTECH will replace the defective diskette or documentation. WinTECH Software disclaims all other warranties, expressed or implied, including without limitation, the warranties or merchantability and of fitness for any purpose. WinTECH Software assumes no liability for damages, direct or consequential, which may result from the use of this program. 2. Listen System Requirements 2.1 Operational Overview Listen is a Windows application designed to monitor serial data communications utilizing the receive line of one or more serial COM ports. Windows 3.1, Windows for Workgroups 3.11, or Windows '95 is required. At least one free serial port is required, however, to be an effective communications monitor two ports are necessary. Listen was designed to operate on RS-232 based systems that utilize software protocols involving half-duplex, block oriented data transmissions whereby data is only transmitted by one device at a time. The RS-232 electrical protocol provides two distinct and physically separate transmit lines between two communicating devices. (i.e. Transmit from Device A to Receive Device B and vice versa.) By tapping in to each of these transmit signals via two separate PC receive lines, Listen can easily monitor all activity between the two original devices, maintaining all timing characteristics, without effecting communications integrity. The communications system being monitored does not have to be RS-232, nor half-duplex in nature. Listen simply enables the receiver for the specified serial port and captures all data that shows up. Multidrop communications protocols, (RS-485, Current Loop, etc.), are available for PC's and should operate with the Listen application using a single serial port. However, since data is identified by the port number on which it is received, all character data would be displayed using the same display attributes, (color & font). 2.2 System/Cabling Requirements This manual assumes RS-232 based communications systems are to be monitored using standard PC Serial hardware. Listen utilizes the standard Windows communications drivers to access the COM ports. This may be somewhat slower than accessing the serial ports directly, but maximizes compatibility across PC platforms. The colors and fonts used to display character data are selectable by the user to best take advantage of the available display technology. Portable PC's are ideally suited for monitoring applications. The passive nature of the Listen design, will not degrade communications performance if the monitoring device proves too slow to capture all the data. Data may be missed by the Listening Device, but the integrity of the original link will be maintained. Cabling requirements for the Listen Application, assuming RS-232, consist of 2 wires for each COM port. The RXD and GND signals, (Receive Data & Ground), for one port are connected to the TXD & GND of a single transmitting device. The RXD & GND for the second port are connected to TXD & GND for the second transmitter. RS-232 control signals, if used, remain in place. Since the TXD signal for one device is always connected to the RXD signal for the other device, all monitoring connections may be made at the same end of the cable. Clipleads are commonly used for cable connections. 2.3 .INI File Parameters The default values for the size of the capture buffer and trap buffer allocated by Listen during startup are 16K bytes and 1K bytes respectively. Global memory is allocated by Listen during startup and returned to Windows on termination of the application. The user may change the allocated buffer sizes by modifying the [MEMORY] section of the Listen.ini file. [MEMORY] BUFFERSIZE = 16 TRAPBUFFERSIZE = 1024 TRAPBUFFERPLACEMENT = MID The capture buffer size is specified in 1K increments up to 64K. The trap buffer size is specified in bytes up to a maximum of 16K. Trap Buffer Placement specifies the position of the trigger with respect to data contained in the trap buffer. The valid selections are: PRE - The trap buffer represents the contents of the capture buffer prior to the trigger point, (i.e. when the trigger occurs, the trap buffer is immediately filled with data existing at the time of the event). MID - The trap buffer represents data surrounding the trigger point. When the trigger condition occurs, half the trap buffer is filled with existing data, with the remainder filled with data received after the trigger. POST - The trap buffer represents data collected immediately after the trigger point. 3. Installation 3.1 Making Backups The distribution diskette is not copy-protected, and the registered user may make backup copies as required. The Listen application may be moved from one PC to another so long as the basic licensing agreement of only one copy in use at a time is maintained. Site licenses are available for commercial users by contacting WinTECH Software. 3.2 Installing Listen Installation of the Listen Application involves simply copying the Listen.exe & Listen.hlp files from the distribution diskette to a working directory on the hard disk. Listen.ini may also be copied if desired. After running the application for the first time, a configuration file will be created on the working directory. Listen.cfg represents the user configurable selections, (character font, colors, baudrate, etc.), in effect at the time the program terminated. These settings will be restored the next time Listen is started. Listen may be started from the program manager, file manager, or program group icon. Consult the Windows user's manual for details. The background Listen display represents a simplistic cabling diagram describing the interconnections between the PC used to monitor serial communications and two separate RS-232 communicating devices. 4. Basic Menu Selections 4.1 ToolBar The Listen toolbar provides convenient access to commonly used functions as described below. The toolbar may be enabled/disabled via a menu option. Open Save Go Stop Copy Print About (New) (Browse) 4.2 Hardware Setup To setup the serial ports in preparation for a monitoring session, activate the Setup, Hardware options from the Listen Main Menu. Listen will present a dialog box containing the current settings for each of the four PC COM ports. Dropdown list box edit controls allow selection of baudrate, parity, number of data bits and number of stop bits for each port. The information for a particular COM port is only displayed if the port is available for use by the Listen application. If the port is not installed, or in use by another Windows application, the associated portion of the dialog box will be greyed, (disabled). Configuration of the hardware characteristics for a serial port does not enable the port for communications. These settings will be used to actually initialize the port whenever a monitoring session is initiated by exercising the New menu option. 4.3 Display Preferences During an active monitoring session, Listen displays data across the screen as it becomes available from the respective communications ports. Configuration options define the colors and fonts used to display this data, as well as the ASCII character representation. 4.3.1 Color & Font Selection To configure the foreground and background colors used to display data from each COM port, select the Setup, Preferences, Colors options from the Listen Main Menu. Listen will respond with a dialog box representing the current color selections for each of the four communications ports as well as the foreground and background colors to be used for block marking operations on captured data. The text marker colors are used during cut and print operations to distinguish the data effected by the operation. The display in the center of the dialog box displays examples of the current pen colors. To change the colors used to represent data received from a given port, press the appropriate foreground or background button and pick a new color from the color selection dialog. Selection of character fonts occurs in much the same way by initiating options under the Setup, Preferences, Fonts branch of the Main Menu. A separate font selection dialog box is activated for each individual Com port. 4.3.2 Non-Printing Character Display The default implementation of Listen displays captured byte data as the ASCII equivalent character codes for data between 033-126, (decimal). This includes all alpha-numeric data plus special keyboard characters such as $, %, etc. Control character data, including the SP character, (000-032), is displayed as a two or three character alpha representation surrounded by square brackets, (such as [SP], [SOH], [ETX], etc.) 8-Bit data is displayed as a bracketed decimal value such as [128], [129], etc. If square brackets are included in the capture data, they are represented as their decimal equivalent, ([91],[93]). Two menu selections allow customization of character data display. Selection of the Setup, Preferences, Num Base menu option will allow the user to configure the numeric base, (Octal, Decimal, Hexadecimal, or Binary), used to display non-printing characters. This option not only effects character display, but also determines how byte data is specified during configuration of filters, triggers, and search strings. If square brackets have some special meaning within the protocol being monitored and the user wishes to use different characters to surround non-printing character data, the Setup, Preferences, Brackets menu option presents a dialog box that allows selection of both the leading and trailing character. Any ASCII code may be selected for the opening and closing bracketing character. They do not have to match and the same code could be selected for both if desired, (i.e. /000/,/128/). Which ever character is selected for use as a bracket, the representation for that character, if it appears in the data stream itself, would always be displayed as a bracketed numeric. For example, using the above illustration, the byte representation of a slash character would be /47/ using the decimal numeric base. 4.4 ASCII Table If the flexibility for configuring the display as described in previous sections is not sufficient, Listen provides the user with the option of explicitly defining the character representation to be used for each byte code. The View, ASCII Table menu selection activates a Listen Child Window that displays the current display settings for each of the 256 byte codes. The ASCII Table displays the numeric values for each byte code in decimal, octal, hex, and binary notation. Scrollbars are supported and the window may be resized and positioned on the screen to maintain as reference during monitoring or browsing operations. Selecting a byte code representation and double-clicking with the left mouse button presents a dialog box that allows the character representation for a given byte code to be modified. Character strings of up to 10 bytes may be used for each code. Any or all character codes may be overridden in this fashion. All changes are maintained in the Listen.cfg file and will remain in effect the next time Listen is started. 4.5 StatusBar The Listen statusbar represents the condition of the trap buffer, trigger status, filter activation status, and enabled COM ports. It may be turned off via a menu selection. 5. Monitoring Data Communications 5.1 Menu Options A monitoring session is initiated by clicking the "Go" button on the toolbar or by selecting the New/Collect option from the Main Menu. If no ports have been enabled, Listen will prompt for the port ids to monitor. If this is a re-initiation of a previous monitoring session, Listen will automatically enable those ports that were in use the last time. Ports are disabled whenever a monitoring session ends, (Browse Enabled), to prevent unnecessary Windows messaging while connected to a live communications system. During a monitoring session, the Files Menu selections change to represent the enabled state of each COM port. To enable or disable a port, simply click on the appropriate menu selection. 5.2 Scrolling Characteristics Listen displays characters to the screen in the font selected for the respective COM port. Since most Windows fonts are variable width, the end of each display line will not necessarily be aligned. If a fixed-width font, (such as Courier), is selected, the end of line may still not be aligned due to the variable number of characters used to display non-printing or user configured character string data. Listen will always attempt to maintain the integrity of the display for each data byte. If the entire character string representation for a data byte cannot be displayed to the end of a display line, Listen will advance to the next line. If different fonts are used for different COM ports, Listen will calculate the y-pixel line height based on the tallest font included in the line. Italicized fonts present some problems when scrolling backward in the Browse mode of operation. The scrolling operation works well, but the entire width of the display line may not be used since Listen calculates the x-pixel coordinates a character at a time in reverse. The calculation for the sum of individual character widths for Italicized fonts is greater than the width calculated for a line containing the same characters, (i.e. the top and bottom of successive characters overlap). 6. Browsing Captured Data 6.1 Browse Menu Options The Browse mode is the startup mode of operation for Listen and is the default mode of operation when not actively monitoring a communications link. Menu options allow the display view to be switched back and forth between the capture and trap buffers. Data may also be saved to a disk file or restored from a previous session. Either memory buffer may be saved to disk. Data may only be restored into the capture buffer. Data is written to disk in a straight byte binary form without color, font, or display preferences. A 128 byte header is used to identify the file as a Listen byte data file and provide details concerning buffer size requirements. Starting at byte 129, data is written in alternating byte locations as data byte followed by port number, (1-4). When restoring a data file, the buffer size information is used to provide a user warning message if the disk file contains more data than will fit in the existing memory buffer. 6.2 Block Operations Block operations are used when displaying a captured buffer to mark a section of data for copy and print operations, or to use as input to the Checksum Calculator. Blocks are marked by clicking the left mouse button on an area of the display and dragging it to the end of the area to be manipulated. Dragging the mouse past the bottom of the display or over the top will cause the display to be automatically scrolled up or down. Marked data blocks are displayed in the foreground/background color specified via the color selection dialog. 6.2.1 Printing Portions of the capture or trap buffers may be printed by selecting a block and pressing the Print menu option. The selected data will be routed to the printer using the same display colors as selected for the screen. These colors may be temporarily adjusted via the color selection menu to allow proper printing using a dot matrix or non-color printer. Byte data will be printed using the default font selection for the printer. The fonts used for display of data to the screen will not be used for the hard-copy. 6.2.2 Copying to Clipboard Portions of data may also be copied to the Windows Clipboard by selecting a block and pressing the Copy menu option. Data is copied to the Clipboard in a block-oriented fashion with data received from different COM ports displayed on different lines. The port identification appears on the front of each line as in the following example: Port 1: [SOH]0001[STX]00120120110[ETX][190][EOT] Port 2: [SOH]0001[STX]READY[ETX]A[EOT] Port 1: [SOH]0010[STX]00009009900990[ETX]F[EOT] Port 2: [SOH]0010[STX]READY[ETX]A[EOT] 6.2.3 Search/Find A marked block of data may also be used as input for the search algorithm. Search may be initiated based on a used defined search string as well. Searches may be performed forward or reverse through the displayed buffer. If a match is found, the buffer is advanced to the appropriate location and the matching block of data is highlighted. 6.2.4 Checksum Calculations During trouble shooting of a communications link, it is often beneficial to double-check a checksum calculation for a string of data bytes to ensure proper response by the receiving device. Listen provides a built-in calculator for several widely used checksums. Marking a block of data and clicking on the appropriate checksum menu selection will generate a dialog box detailing the results of the calculation. 7. Using Filters 7.1 Byte Filters Listen supplies four byte filters, one for each COM port. Each byte filter consists of an eight bit mask that may be applied to all incoming data to prevent selected data from entering the capture buffer. Each bit in the mask is specified with either a '1', '0', or "don't care" designation. If a Byte Filter is enabled for a given COM port, Listen compares each byte received with the bit mask and excludes all data that fails the comparison. The Setup, Filters, Bytes menu selections generate a dialog box that displays the current settings for each bit mask with an enable/disable check box. Selecting the button corresponding to one of the four COM ports allows the bit mask to be changed. Each check box associated with a data bit represents one of three states. A checked box equates to a '1'. An unchecked box equates to '0'. If the "Apply to All Ports" option is used, the specified bit mask will overwrite the current selection for all four COM ports. 7.2 Block Filters Block filters may be used in protocols operating in half-duplex mode. A block filter consists of a string of bit masks applied to the start of each data communications block. The start of a block is always identified by a transition of data direction as determined by the port identification of the data received. Timing of data transmissions has no effect on the determination of the start of a block. Listen simply compares the port number of each data byte received with the port identification of the last byte received, and if it's different begins a new block filter comparison. As an example, assume the protocol being monitored operates as follows: Device A transmits 10 bytes to Device B. Device B transmits a single byte acknowledgment. Device B then transmits a 10 byte response back to A. Device A acknowledges the response. If Listen is connected to Device A via port 1 and Device B via port 2, it would receive 10 bytes from A, followed by 11 bytes from B, followed by 1 byte from A. This would be interpreted as three data blocks. If Device A initiates a new message to B, Listen would assume the data is a continuation of block #3. Since the port identification is used to determine block transitions, block filters may not be used in applications using a single COM port to monitor communications. To configure block filters, select the Setup, Filters, Block menu options. Block filters may be enabled/disabled by simply checking the associated box in the dialog described above. Modifications to the byte string may be made by selecting the appropriate port button. Byte strings may be entered to specify block filters in the same format as used by Listen to display byte data. Alpha-Numeric characters, bracketed control characters, or bracketed numeric values may be used. In addition, bit patterns may be specified by entering a bracketed 8 digit notation representing a binary value, (i.e.[1010xxxx]). As with byte filter specification, a single block filter may be applied to each COM port by checking the appropriate box in the specification dialog. 8. Trap Buffer Operation 8.1 Trap Buffer Operation Listen makes available a block of memory separate from the normal capture buffer called a trap buffer. The purpose of the trap buffer is to obtain and maintain a "snapshot" of the capture buffer based on a configurable event called a trigger. The trigger is a string of data bytes, (including don't care bit masks), which is compared to received data for determination of the event. When triggered, data is copied from the capture buffer to the trap buffer and held indefinitely, or until the same trigger event occurs again. Continued data collection will eventually wrap around the capture buffer, but the contents of the trap buffer is always available for browsing. This provides an effective trouble-shooting aide for trapping infrequent communications faults. 8.2 Trigger The trigger is specified in a dialog box similar to that used for byte string entry for block filters. Data may be entered as alpha-numeric characters or as bracketed numeric values. Bit patterns may be entered in bracketed binary notation using 'X' for don't care bits. A trigger comparison may be associated with data received from a specific port or a global comparison may be made with data received from any COM port. A trigger comparison does not have to begin with the start of a data block, but may not span data from two devices. A block transition will always reset the comparison logic counters. 8.3 Browsing the Trap Buffer A menu selection available from the Listen Main Menu allows the browse display to be switched between the capture and trap buffers. 9. Technical Support 9.1 Contacting WinTECH If it ever becomes necessary to contact WinTECH concerning a technical question or to offer comments or suggestions for improving the Listen application please call or write to the address below: WinTECH Software P.O.Box 907 Lewisburg, WV 24901 (304) 645-5966 For quickest response, email questions/comments to: listen@win-tech.com